# ################################################################### # Vince's Additions - an extension package for Alpha # FILE: "ElecCompletions Help" # created: 1/8/97 {2:24:21 pm} # last update: 26/2/1999 {8:17:54 pm} # Author: Vince Darley # E-mail: # mail: Division of Engineering and Applied Sciences, Harvard University # Oxford Street, Cambridge MA 02138, USA # www: # Copyright (c) 1997-99 Vince Darley # Some pieces pasted from Alpha-D mailing list responses. # ################################################################### The idea with electric completions is to save you key strokes. When you hit cmd-tab Alpha tries to expand what you have just typed to give the rest of what you want (the choice of cmd-tab can be adjusted in the 'Config->Global->Special Keys' dialog). If you want basic help/tutorial information, do the following: when you're in a mode for which you want a tutorial on electric completions, select 'Completions Tutorial' from the 'Mode Prefs' menu. Follow the instructions there. You can modify the following preferences using the 'Config->Global->Flags->Electrics' menu item: useElectricMenu --- use electric template menu showElectricsInMenu --- show electric completions in menu showElectricKeysInMenu --- show electric key bindings in menu modeSpecificElecTab --- use mode-specific electric tab electricTab --- use electric tab templateStopColor --- colour of template stops listPickIfMultExpds --- similarly for expansions ElectricFillers --- The format of the template stops: 0 = just use bullets 1 = use bullets but signal the name in the status window 2 = insert names into the window with the bullets 3 = insert names and highlight into the window with the bullets maxTemplateNesting--- level of nesting we allow before clearing The electric menu contains a 'Templates' sub-menu, which contains global templates stored in the variable 'univ::MenuTemplates', and mode-specific templates stored in variables ${mode}Templates. The format of these variables is a list of names, which correspond to procedures when prepended with 'file::'. You can add new items by using the menu item. Templates Many of the routines in Vince's Additions allow you to insert templates for 'for' loops, '\begin...\end environments', file headers, function comments, and even entire documents. This section details the features of Vince's Additions which allow you to do that. Here's an example of a 'for' template in C++ mode (created just by typing 'for'): for ( ; ; ){ Once a template has been inserted, it will often contain a number of 'place-markers' or 'template-stops' at each of which you will most likely wish to enter some text/code. You can jump backwards and forwards amongst these stops using a set of key bindings. You have a choice between two basic sets (you select using the 'Electric Bindings' dialog): Operation Standard Bindings Alternative Set "Next Stop Or Tab" Tab ctrl-j "Complete" cmd-Tab cmd-Tab "Expand" cmd-Space Tab "Prev Stop" shift-Tab shift-ctrl-j "Real Tab" opt-Tab opt-Tab "nth Stop" ctrl-Tab ctrl-opt-j "Clear All Stops" shift-ctrl-Tab shift-ctrl-opt-j Furthermore you can redefine any of these bindings using that same dialog. You have a choice between four different formats for the visual appearance of the template-stops. They are usually signified by a bullet ' ', but more elaborate methods are supported. These templates may be nested without any extra effort on your part. Most of this code is contained in the file "betterTemplates.tcl", although all the bindings and initialisation are in "elecBindings.tcl". Look at the new 'electric' menu for a list of these bindings, together with some other functions. ================================================================================ Completions I've now written a unified collection of procedures to address command completion, code indentation, electric-code generation, word completion and related facilities (incorporating my old TeX-reference completion for example). Here's a typical example from TeX mode, I type: for an explanation of this phenomenon, please refer to Fig The signifies that Vince's Additions should try to complete the currently typed text. In this case the completion is: for an explanation of this phenomenon, please refer to Figure~\ref{fig- If I hit again, Vince's Additions tries to search for TeX '\labels' which begin with 'fig-' to insert the first such label it finds into the text: for an explanation of this phenomenon, please refer to Figure~\ref{fig-heat-vs-time} If this is the wrong one, I can keep hitting until I reach the correct completion: for an explanation of this phenomenon, please refer to Figure~\ref{fig-explanation} Here's an example from C/C++ modes. I type 'for' and get: for (; This works at any current level of indentation, and the bullet marks ' are placemarkers. You can just press 'Tab' (without 'cmd') to jump from one to the next. These facilities are activated as follows: Tab --- plain - either 'indent' or 'next template mark' cmd - complete the current text. opt - insert a real tab. So, pressing Tab by default will _not_ necessarily insert a tab, rather it will indent the current line of code to the correct indentation level to match the code around it. Types of completion Command-Tab has a number of different meanings, which will be explained below. Completions are listed in order of precedence. User completion: all entries defined in the array 'userCompletions' are checked and inserted if appropriate. This is useful to make 'vmd' turn into 'Vince Darley', or 'www' into my home-page url, or ... User completions are active in all modes, and take precedence over all other completion types. Context sensitive completion: Context sensitive completions are mode dependent. In some modes you can tell relatively easily from the context whether a particular 'word' is a variable or procedure name or... If different completion procedures are useful for different types of word, then they are checked next. For instance, in Tcl mode, a word beginning with '$', or preceded by 'set' or 'global' is a variable name. It should therefore be completed preferentially as a variable, rather than being expanded as a command. E.g. $str should normally not be expanded to '$string ...' since it's clearly not the command 'string' that the user is trying to type. Command completion: For instance: type 'str' and it is completed to 'string' (in Tcl mode). If there are multiple possibilities then the longest unique prefix is inserted. The available completions are mode dependent, and stored as a large string in the variable ${mode}cmds. They must be stored alphabetically, and be separated by whitespace. THERE IS NO LONGER A NEED TO BEGIN AND END THE LIST WITH WHITESPACE. Here is the default value for Tcl mode: set Tclcmds { append array catch close concat continue elseif error for foreach format lindex lsearch lsort regexp regsub rename return string switch while } Ensemble completion: type 'string co' and a complete template for code is generated (example for C mode): for (; You can move from one template mark ' ' to the next with, plain 'Tab' - I automatically sense whether a template insertion is in progress or not and interpret tab accordingly. These are again mode dependent. Each is stored individually as an element of the array ${mode}electrics, so, for instance the above electric code is generated by: set Celectrics(for) " ( )\{\n\t \n\}\n Note how the bullets are double in the definition. You can actually place an explanatory bit of text between pairs of bullets. This is then used as a hint to the user: set Celectrics(for) " ( start increment )\{\n\t \n\}\n Class name completion: In C++ mode, when entering a class definition, the class name occurs multiple times. To save entering all of these, this completion will fill them all in for you. It works like this: type 'class' class : public { public: ( ); (void); Now type the class name, say 'toaster', followed by . This will result in: class toaster : public { public: toaster( ); ~toaster(void); i.e. each occurrence of the electric stop 'object name' has been filled in correctly. This feature may be easily extended to more complex examples. TeX reference completion: type '\ref' and the command is automatically completed with the name of a nearby \label{}. Repeated keypresses will cycle through all \label's. Further, these commands chain together, so typing '\eqr' will complete the \eqref and continue to fill in a nearby label! These were explained above. Note that the reference completions can be instigated by command completion on, 'Fig' 'Chap' 'Eq.' 'Sec', ... which insert the standard label prefix 'fig:' 'chap:' 'eq:' 'sec:' as appropriate. If you complete with no prefix, then any label will match; if you have a prefix then only those which match will be suggested. TeX citation completion. Type '\cite{Darley19' and the command is completed with a matching citation entry from one of your '.bib' database files. If there are multiple possibilities, then you are prompted with a list from which to choose. (Note: if you find the selection box a bit narrow, it is possible to edit Alpha using ResEdit to increase its size). Depending upon the value of a TeX flag, the list can include the titles of each choice, making it more obvious to you which is correct. TeX environment completion: \begin{} \end{} pairs with synchronisation of the parameter, and template generation of the body. You can complete '\begin' followed by 'equ' to the following: \begin{equation} \label{eq: \end{equation} You have a choice between the double-completion, as above, or just typing '\begin{equation}' which will do the job in one go. Similar things work for 'itemize' 'enumerate' etc. Of particular use are the completions for 'figure' environments, from which you can enter ordinary figures, floating figures, and a large number of sub-figure configurations (2 figures side-by-side, a block of 4,...). For instance, a handful of key-presses will give you this: \begin{figure} \centering \subfigure[ subfig caption ]{\label{fig: \includegraphics[width=\figstwo]{ graphics file }}\goodgaptwo \subfigure[ subfig caption ]{\label{fig: \includegraphics[width=\figstwo]{ graphics file \subfigure[ subfig caption ]{\label{fig: \includegraphics[width=\figstwo]{ graphics file }}\goodgaptwo \subfigure[ subfig caption ]{\label{fig: \includegraphics[width=\figstwo]{ graphics file \caption [short caption for t.o.f.] caption \label{fig: \end{figure} For these to work, you must use the correct LaTeX packages (graphics, floatingfigure or subfigure as appropriate, although the code will automatically insert the correct 'usepackage' specifications for you if desired), and you may need the following definitions in your LaTeX preamble: \newlength{\goodspace} \newlength{\goodspacethree} \newlength{\goodspacefour} \newlength{\figstwo} \newlength{\figsthree} \newlength{\figsfour} \setlength{\goodspace}{\subfigtopskip+\subfigbottomskip} \setlength{\goodspacethree}{\goodspace} \setlength{\goodspacefour}{\goodspace*\real{0.6}} \newcommand{\goodgap}{\hspace{\goodspace}} \newcommand{\goodgaptwo}{\goodgap} \newcommand{\goodgapthree}{\hspace{\goodspacethree}} \newcommand{\goodgapfour}{\hspace{\goodspacefour}} \setlength{\figstwo}{(\linewidth-\goodspace)/2-1pt} \setlength{\figsthree}{(\linewidth-\goodspace *2)/3-1pt} \setlength{\figsfour}{(\linewidth-\goodspace *\real{1.8})/4-1pt} These allow good alignment and spacing for most subfigure combinations without the need for manual intervention. Some environments can contain an arbitrary number of items. In this case, hitting 'shift-option-i' will add an item. Here we turn this: \begin{description} \item[First one] here's the description \item[ description \end{description} into: \begin{description} \item[First one] here's the description \item[ \item[ description \end{description} Similar entries work correctly for itemised, enumerated, aligned,... environments. File-name completion: Useful for Shel mode, this allows you to type a partial directory or filename and hit cmd-Tab to have it extended as much as possible. Tcl Variable Completion: Tcl variables are often referenced with '$var' or just 'var' or '${var}'. You can complete between any of these types. A local search for a match is done and the closest match inserted. Again you can cycle through other matches with Word Completion: if none of the above succeeded then the current word is completed to copy nearby words (variable names) in the file. Again, repeated presses will cycle through other possibilities. In any form of text in any mode, if no mode-specific completion matches, then any local word can match, complete and be cycled through as usual. Template insertion You'll notice in a lot of the above examples that bullets ' ' are inserted into the text. In fact the user has a choice of four different levels of interaction with the template insertion procedures. You can change this using the universal preferences dialog (in the config menu). You can move from one insertion point to the next using the 'tab' key; move backwards with 'shift-tab' and jump to any insertion point with 'ctrl-tab'. If you don't like these key bindings, an alternative set is available by a change in the universal preferences. You can also choose the colour of the inserted bullets/prompts. The Electric Menu By default all items in the ${mode}electrics array are inserted into a new menu. This allows you to insert them, and get a feel for a small number of the completions which exist. Also at the bottom of the menu are items for each of the standard key bindings these routines use, to help you to remember them. Completion feedback Help me to help you! Completions for some common items just don't currently exist. So if you try to complete something and it doesn't work, why not write a completion for it? Once you have assembled a few, mail them to me (preferably binhex'd, since bullets ' ' don't travel well by ASCII mail). I'd particularly like completions for other modes. Speed Alpha has some limitations which means some aspects of Vince's Additions are a little bit slow (on low-end machines, at least). Two things you can do to alleviate this: first, in modes for which Tab (or ctrl-j under the alternative bindings) ALWAYS means to go the next template stop and never means to indent the current line, define a new mode variable 'tabNeverIndents' by adding the following line to your "prefs.tcl": newPref f tabNeverIndents 1 MODE where 'MODE' is 'TeX', 'Java', 'HTML' or whatever. You'll need to add one such line for each relevant mode. ================================================================================